Release 10.1A: OpenEdge Application Server:
Developing AppServer Applications

AppServer session access

You can publish entry points (remote procedure pathnames) that control access to an AppServer session at run time using the EXPORT( ) method on the SESSION handle. Publishing an export list limits the remote procedures that a client application can execute to those that you specify with this method. Because this is a run-time operation, you can change the list at any time that your application requires, and you can reset the list to empty, allowing access to the entire set of procedures available from the current AppServer PROPATH setting.

However, setting this list applies only to the AppServer session in which you execute the EXPORT( ) method. This means that you might have to manage the list differently in your application depending on the operating mode that you configure for the AppServer.

Note: As this is a context management problem, the only way to effectively manage this kind of information for a session-free AppServer is to maintain your own context database for it. Therefore this section applies only to session-managed AppServers.

For more information on setting and resetting entry points in an AppServer session, see Chapter 2, " Programming the AppServer."

Operating mode interactions

Because of how the EXPORT( ) method and AppServer operating modes work together, you must use it differently, depending on your AppServer operating mode. When you invoke the method with a list of procedure names, the method adds this list to any existing list of entry points that you have previously specified for an AppServer session.

If the AppServer is running in state-reset operating mode, each AppServer agent automatically resets any export list to empty with each new connection. However, if the AppServer is running in state-aware or stateless operating mode, you must manage all setting and resetting of entry points manually. Otherwise, each time you execute the method with a list of procedure names, they are added to the existing list of entry points. Thus, unless you explicitly reset the list, on a state-aware AppServer, the number of entry points set for an AppServer agent can grow with each client connection, and on a stateless AppServer, the number can grow with each client request.

How to set and reset an export list for each operating mode

Each AppServer operating mode requires a different arrangement for setting and resetting the published entry points during an AppServer session:

State-reset operating mode — You can set an export list any time before a client application uses them; you never need to reset your export list from one connection to the next.
State-aware operating mode — You can set an export list any time before a client application uses them; if you set them in remote procedures, you probably want to reset them with each connection.
Stateless operating mode — You can set an export list any time before a client application uses them; you generally set them in the Startup procedure for the entire AppServer session. You can also set them with a finer degree of session granularity, but you must exercise caution when doing so.
State-free operating mode — You can most practically set an export list only in the Startup procedure for the entire AppServer session. You can also set them with a finer degree of session granularity, but you must exercise caution and consider the connectionless nature of state-free remote requests when doing so.

State-reset operating mode

When the connection terminates on a state-reset AppServer, the export list for the disconnected AppServer agent is automatically reset to empty. Thus, you must set any export list on a state-reset AppServer for each new connection and in some procedure that is guaranteed to be executed when you need to have the list set.

You might want to set the export list in the Connect procedure if you know the export list criteria at the start of each connection. The criteria can be based on the user or any other information that you determine at the time of connection. Otherwise, you must set or reset the list in some remote procedure executed by the client.

State-aware operating mode

For a state-aware AppServer, you can conveniently set a single export list for all AppServer agents, regardless of the connection, using the Startup procedure. Otherwise, you can set it, like on a state-reset AppServer, in the Connect procedure or some remote procedure executed by the client.

When the connection terminates on a state-aware AppServer, the disconnected AppServer agent maintains the last setting of the export list. If you want the export list to be empty at the start of every connection, you must explicitly reset the list at some point between connections. You can guarantee this for every AppServer session by resetting the list in the AppServer Connect or Disconnect procedure, as shown:

ret = SESSION:EXPORT(). /* Reset to empty */

Stateless operating mode

For a stateless AppServer, you can conveniently set a single export list for all AppServer agents (global to the AppServer session), using the Startup procedure. Because export list settings apply only to the AppServer agent in which they occur, setting and resetting an export list at any other point on a stateless AppServer requires careful attention.

Caution: Setting an export list during remote procedure requests to a stateless AppServer is an error-prone activity. If your application requires this fine degree of control, the rest of this section explains how you can do it. However, you might consider implementing your AppServer using state-aware operating mode, instead.

Like a state-aware AppServer, once you set an export list, the list remains set in the AppServer session until you reset it. For an unbound connection, because you cannot guarantee when an AppServer agent will execute what procedure, you must manage any export list settings appropriately during each request. If you do not, you can leave an unpredictable set of export list settings across AppServer agents in the AppServer pool.

For an unbound connection, you can maintain consistent export list settings using the Connect, Activate, and Deactivate configuration procedures. This is especially useful to provide user-based access control.

To maintain consistent export list settings using the Connect, Activate, and Deactivate configuration procedures:

In the Connect procedure, establish an export list based on the authenticated user.
Save the export list using stateless context storage, such as the SERVER-CONNECTION-CONTEXT attribute or a context database.
In the Activate procedure, retrieve the export list from your stateless context storage and set it using the EXPORT( ) method. The list is now set to filter the current remote procedure call and ensure its validity for the user.
In the Deactivate procedure, reset the export list to empty or to any other global session value using the EXPORT( ) method. This leaves the AppServer agent to handle remote procedures calls from all connections, as appropriate.
Note: The Disconnect procedure is not effective to reset a user-based export list, especially for an unbound connection, because the Disconnect procedure can run in an AppServer agent other than the one where the last export list setting occurred.

You can also use the Activate procedure to make application-based settings, where you set the list depending on some application state other than the authenticated user. In this case, you might determine the setting indirectly from stateless context storage or from some other source available to the Progress 4GL. For more information on using stateless context storage, see Chapter 2, " Programming the AppServer."

State-free operating mode

For a state-free AppServer, you cannot perform these functions at connect time at all, because the client maintains no physical connection to any one AppServer, and the AppServer never runs a Connect procedure. For state-free AppServers, setting an export list and database connections works much more effectively as a global activity that you implement in the Startup procedure, which executes for every AppServer agent when it starts up. However, note that the criteria for initializing the export list cannot easily be user-based, as there is no connected user.

You can pass request-based export list information to each AppServer agent that handles a remote procedure request. The AppServer agent can retrieve and resave the export list information for the next AppServer agent that handles the client using the Activate and Deactivate procedures.

Caution: Setting an export list during remote procedure requests to a state-free AppServer is an error-prone activity. If your application requires this fine degree of control, the rest of this section explains how you can do it. However, you might consider implementing your AppServer using state-aware operating mode, instead.

To maintain consistent export list settings using the Activate and Deactivate configuration procedures:

In the Startup procedure, establish an initial export list based on whatever criteria your application requires (for example, the time of day).
Save the initial export list using state-free context storage, such as a context database or operating system file. This context storage must be accessible to all AppServers registered to handle the same state-free application service.
In the Activate procedure, retrieve the export list from your state-free context storage and set it using the EXPORT( ) method. The list is now set to filter the current remote procedure call and ensure its validity according to whatever criteria you determine for the request.
In the Deactivate procedure, reset the export list to empty or to any other global session value using the EXPORT( ) method and resave the reset export list to your state-free context storage. This leaves the current or any other AppServer agent in any AppServer that supports the state-free application service to handle future remote procedure requests, as appropriate.